<html>
   <!-- $Id: properties.html,v 1.3 2006/07/13 08:54:39 grlea Exp $ -->
   <head>
      <title>Simple Log Properties</title>
      <meta http-equiv="description" content="Documentation of the properties accepted by Simple Log" />
      <link type="text/css" rel="stylesheet" href="style.css" />
      <link type="text/css" rel="stylesheet" href="code.css" />
   </head>

   <body>

      <div class="topMenu">
         <h1>Simple Log User Guide</h1>
         <ul>
            <li><a href="quickStart.html">Quick&nbsp;Start</a></li>
            <li><a href="philosophy.html">Philosophy</a></li>
            <li><a href="recommendedUse.html">Recommended&nbsp;Use</a></li>
            <li><a href="properties.html">Properties</a></li>
            <li><a href="rollover.html">Log&nbsp;Rolling</a></li>
            <li><a href="log4jComparison.html">Comparison&nbsp;with&nbsp;Log4J</a></li>
            <li><a href="faq.html">FAQ</a></li>
            <li><a href="donations.html">Donations</a></li>
            <li><a href="meaningOfLife.html">The Meaning of Life</a></li>
            <li><a href="api/index.html">API Documentation</a></li>
         </ul>
      </div>

      <h1>Simple Log Properties</h1>

      <img src="images/controlKnob.png" alt="Lost?" class="illustration"/>

      <p>
         This page documents all the properties that can be set to configure Simple Log.
      </p>

      <p>
         Technically, you don't really need this page.
         Except for the system properties at the beginning, all the documentation here is
         found in the Simple Log configuration files.
      </p>

      <p>
         Don't you think it makes more sense to have the documentation of the properties <b>with</b> the actual properties, rather than in the fourth page of the user guide.
      </p>

      <p>
         Anyway, if you crave the comfortable lustre of HTML, this page is here for you, any time you need it.
         That's what friends are for.
      </p>

      <h2>System Properties</h2>

      <p>
         Simple Log responds to the following System Properties, which can be defined either
         using the -D command line argument to your Java Virtual Machine, or by calling
         <span class="code">System.setProperty()</span>.
      </p>

      <a name="simplelog.dev.debug"/>
      <h3 class="propertyName">simplelog.dev.debug</h3>

      <p>
         Setting this property to <span class="configuration">true</span> will result in Simple Log
         itself outputting debugging information. This option is particularly useful if you find
         yourself in the scenario where Simple Log isn't creating any output and you think it should
         be. The output will be written to <span class="code">System.err</span> and will look similar
         to the following example.
      </p>

<pre class="output">
SimpleLog [dev.debug]: Simple Log DEV Debugging enabled (-Dsimplelog.dev.debug)
SimpleLog [dev.debug]: Creating default SimpleLog instance
SimpleLog [dev.debug]: System property 'simplelog.configuration': null
SimpleLog [dev.debug]: Attempting to load default properties (simplelog.properties) from classpath
SimpleLog [dev.debug]:
SimpleLog [dev.debug]: FAILED to load any SimpleLog configuration.
SimpleLog [dev.debug]:
SimpleLog [dev.debug]: NO LOG OUTPUT WILL BE GENERATED.</pre>

      <h3 class="propertyName">simplelog.dev.printStackTraces</h3>

      <p>
         Normally, if Simple Log encounters an internal error, it will print a message to
         <span class="code">System.err</span> and, where necessary, the type and message exception
         that caused the error. Setting this property to <span class="configuration">true</span>
         will cause the stack trace of the exceptions to also be printed in these circumstances.
      </p>

      <h2>Debug and Trace Levels</h2>


      <h3>Debug Levels</h3>

      <p>
         Debug levels for classes and packages are defined simply by entering a fully-qualified class or
         package name and making the value either the number or name of one of Simple Log's DebugLevels.
         (Note that the '=' is optional in Java properties files).
      </p>

      <p>
         When the name of a debug level is used:
         <ul>
            <li>the "Lx_" prefix from the field name is NOT used (e.g. the name of L1_FATAL is "FATAL");</li>
            <li>the names are case-insensitive (i.e. "FATAL" = "Fatal" = "fatal")</li>
         </ul>
      </p>

      <p>
         The debug level for a class is acquired hierarchically:
         First the class name is sought, then its package, then its parent package, etc.
         If no level is found for a class or any of its containing packages, the default level is used.
      </p>

      <p>
         Levels are defined as:<br/>
         (see org.grlea.log.DebugLevel javadoc for details)
         <ul>
             <li>1 = Fatal</li>
             <li>2 = Error</li>
             <li>3 = Warning</li>
             <li>4 = Info</li>
             <li>5 = Debug</li>
             <li>6 = Verbose</li>
             <li>7 = Ludicrous</li>
         </ul>
      </p>

      <p>
         Example: if we wanted the following configuration:
         <blockquote>
            org.grlea.application.ApplicationMain:       Verbose<br/>
            All other 'org.grlea.application' classes:   Debug<br/>
            All other 'org.grlea' classes:               Error<br/>
         </blockquote>
         then we could use either the properties:
         <blockquote>
<pre>org.grlea.application.ApplicationMain 6
org.grlea.application 5
org.grlea 2</pre>
         </blockquote>
         OR the properties
         <blockquote>
<pre>org.grlea.application.ApplicationMain = verbose
org.grlea.application = debug
org.grlea = error</pre>
         </blockquote>
      </p>

      <h4>Inner Classes</h4>

      <p>
         Debug levels and trace flags for inner classes can be specified using either the dollar sign ('$')
         that javac puts in the name or just the normal period ('.') that you use to access them in code.
      </p>

      <h4>Instance Loggers</h4>

      <p>
         If you are using instance loggers, you can specify levels for particular instances by appending
         to the class name a period ('.') and the string representation of the instance ID.
      </p>

      <p>
         Example: To log the 'InstanceObject' instance with instance ID 'Special' at the Verbose level
         and all other InstanceObject instances at the Error level, you would write:

         <blockquote>
<pre>org.grlea.application.InstanceObject.Special = verbose
org.grlea.application.InstanceObject = error</pre>
         </blockquote>
      </p>


      <h3>Tracing Flags</h3>

      <p>
         Tracing flags are set in the same manner as debug levels (you just need the
         fully-qualified class or package name and a value) except that:
         <ul>
            <li>the string '<code>#trace</code>' (without the quotes) must be appended to the class or package name; and</li>
            <li>the values are <code>true</code> or <code>false</code></li>
         </ul>
      </p>

      <p>
         Example:
         <blockquote>
<pre>org.grlea.application.ApplicationMain#trace true
org.grlea.application#trace false</pre>
         </blockquote>
      </p>


      <h3 class="propertyName">simplelog.defaultLevel</h3>

      <p>
         Default level for classes for which no debug level hierarchy exists:
         Same values as for debug levels (1 to 7 or Fatal, Error, Warn, Info, Debug, Verbose or Ludicrous)
      </p>

      <p>Default: <code>4</code> <i>(Info)</i></p>


      <h3 class="propertyName">simplelog.defaultTrace</h3>

      <p>Default tracing for classes for which no tracing hierarchy exists: true or false</p>

      <p>Default: <code>false</code></p>



      <h2>Import List</h2>

      <h3 class="propertyName">simplelog.import</h3>

      <p>
         A comma-separated list of other properties files to import.
         The files must be in the classpath.
         This property only works when it is in the primary simplelog.properties file.
      </p>

      <p>
         Note that if a property is specified in more than one file, its value will be sourced from
         the last file (in the list) that it appears in.
      </p>

      <p>Default: <code>simplelog-config.properties,simplelog-rollover.properties</code></p>



      <h2>Log File Properties</h2>


      <h3 class="propertyName">simplelog.logFile</h3>

      <p>
         Send log output to a file (rather than to System.err): relative or absolute file name.
      </p>

      <p>
         If the <code>interpretName</code> property is true (default), the file name will be interpreted using a
         MessageFormat, with argument 0 being the current Date. This allows the date to be inserted into
         the file name using patterns like {0,date,yyyy_MM_dd} or {0,date,yyyy} and {0,date,MM}, etc.<br/>
         Note that the name will NOT be interpreted if log rolling is active.
      </p>

      <p>
         Relative paths are relative to the JVM's working directory.
         Non-existing directories are created.
         Output falls back to System.err if the file name can't be interpreted or the file can't be
         opened for writing.
      </p>

      <p>Default: <i>blank (write to System.err)</i></p>


      <h3 class="propertyName">simplelog.logFile.interpretName</h3>

      <p>
         Whether the logFile property should be interpreted using a MessageFormat: true or false
         See the description for simplelog.logFile above for more details.
      </p>

      <p>
         This property has no effect when log rolling is in use. The log file name will not be translated.
      </p>

      <p>Default: <code>true</code></p>

      <h3 class="propertyName">simplelog.logFile.append</h3>

      <p>
         When writing log output to a file, append to the file if it already exists: true or false
      </p>

      <p>
         This property has no effect when log rolling is in use. An existing active log file will always be appended.
      </p>

      <p>Default: <code>true</code></p>


      <h3 class="propertyName">simplelog.logFile.andConsole</h3>

      <p>
         Whether the logging output going to a file should also be output to the console: true or false
         Only applies when simplelog.logFile is assigned.
      </p>

      <p>Default: <code>false</code></p>



      <h2>Configuration Management</h2>

      <h3 class="propertyName">simplelog.reloading</h3>

      <p>
         Reload the properties if they change: true or false
      </p>

      <p>Default: <code>false</code></p>



      <h2>General Format Properties</h2>


      <h3 class="propertyName">simplelog.printStackTraces</h3>

      <p>Whether the exception message should print a stack trace: true or false</p>

      <p>Default: <code>true</code></p>


      <h3 class="propertyName">simplelog.dateFormat</h3>

      <p>
         Date format for ALL message formats: see
         <a href="http://java.sun.com/j2se/1.4/docs/api/java/text/SimpleDateFormat.html">
            java.text.SimpleDateFormat
         </a>
      </p>

      <p>Default: <code>EEE yyyy/MM/dd HH:mm:ss.SSS</code></p>



      <h2>Specific Format Properties</h2>

      <p>
         Message formats for each type of logging: see
         <a href="http://java.sun.com/j2se/1.4/docs/api/java/text/MessageFormat.html">
            java.text.MessageFormat
         </a>
         Note there is a different format for SimpleLoggers created on a per-instance basis.
      </p>

      <p>
         The common message arguments are:

         <ul>
            <li>{0} = Current date/time (java.util.Date)</li>
            <li>{1} = Thread name (String)</li>
            <li>{2} = Class name (String)</li>
            <li>{3} = Instance ID (Object)</li>
            <li>{4} = Debug level (DebugLevel)</li>
         </ul>
      </p>

      <p>
         The uncommon message arguments are:

         <ul>
            <li>debug:          {5} = message</li>
            <li>debugObject:    {5} = object name, {6} = object value</li>
            <li>debugException: {5} = exception</li>
            <li>entry:          {5} = method name</li>
            <li>exit:           {5} = method name</li>
         </ul>
      </p>


      <h3 class="propertyName">simplelog.format.*</h3>

      <p>
         These are the default values for the formats for each non-instance message type.
      </p>

      <p><pre>simplelog.format.debug =           {0}|   |{1}|{2}|{5}</pre></p>
      <p><pre>simplelog.format.debugObject =     {0}|---|{1}|{2}|{5}|{6}</pre></p>
      <p><pre>simplelog.format.debugException =  {0}|***|{1}|{2}|{5}</pre></p>
      <p><pre>simplelog.format.entry =           {0}|&gt;&gt;&gt;|{1}|{2}|{5}</pre></p>
      <p><pre>simplelog.format.exit =            {0}|&lt;&lt;&lt;|{1}|{2}|{5}</pre></p>

      <h3 class="propertyName">simplelog.format.*.instance</h3>

      <p>
         These are the default values for the formats for each instance message type.
      </p>

      <p><pre>simplelog.format.debug.instance =           {0}|   |{1}|{2}[{3}]|{5}</pre></p>
      <p><pre>simplelog.format.debugObject.instance =     {0}|---|{1}|{2}[{3}]|{5}|{6}</pre></p>
      <p><pre>simplelog.format.debugException.instance =  {0}|***|{1}|{2}[{3}]|{5}</pre></p>
      <p><pre>simplelog.format.entry.instance =           {0}|&gt;&gt;&gt;|{1}|{2}[{3}]|{5}</pre></p>
      <p><pre>simplelog.format.exit.instance =            {0}|&lt;&lt;&lt;|{1}|{2}[{3}]|{5}</pre></p>


      <h2>Log Rolling Properties</h2>

      <h3 class="propertyName">simplelog.rollover</h3>

      <p>
         Enables the rolling of log files, using the specified strategy.
         Valid values are '<code>fileSize</code>', which performs file size-based rollover, '<code>timeOfDay</code>', which performs
         time-based rollover, or the name of any concrete implementation of
         <a href="http://www.grlea.org/javadoc/simple-log/org/grlea/log/rollover/RolloverStrategy.html">
            org.grlea.log.rollover.RolloverStrategy
         </a>.
         Note that the RolloverStrategy implementation must contain a zero-argument constructor.
      </p>

      <p>Default: <i>blank (no rollover)</i></p>


      <a name="simplelog.rollover.directory"/>
      <h3 class="propertyName">simplelog.rollover.directory</h3>

      <p>
         When rollover is in use, specifies the directory, either absolute or relative to the working
         directory, into which rolled-over log files should be moved.

         If this property is not specified, rolled-over log files will be stored in the same location as
         the active log file.
      </p>

      <p>Default: <i>blank (same directory as active log file)</i></p>


      <a name="simplelog.rollover.filename"/>
      <h3 class="propertyName">simplelog.rollover.filename</h3>

      <p>
         When rollover is in use, specifies the format of the file name to use for rolloed-over log files.
      </p>

      <p>
         The message arguments are:
         <ul>
            <li>{0} - The Date at which the rolled-over file was created (i.e. the time the log file ended).</li>
            <li>{1} - An incrementing hexadecimal number giving the log file a unique file name within the
                directory into which it is being output.</li>
         </ul>
      </p>

      <p>
         If you should want to keep only one rolled-over log file (in addition to the active log), you may emit
         both variabes from the name (e.g. tomcat-rolled.log) and the file will be overwritten each time
         the active file is rolled.
      </p>

      <p>
         Example:
         <blockquote>
            <table>
               <tr>
                  <th>Rollover Filename Pattern</th>                        <th>Example Results</th>
               </tr>
               <tr>
                  <td><code>tomcat-{1}.log</code></td>                      <td><code>tomcat-1A.log<br/>
                                                                                      tomcat-1B.log</code></td>
               </tr>
               <tr>
                  <td><code>tomcat-{1}-{0,date,MMM_dd}.log</code></td>      <td><code>tomcat-1A-Oct_24.log<br/>
                                                                                      tomcat-1B-Oct_25.log</code></td>
               </tr>
            </table>
         </blockquote>
      </p>

      <p>Default: <code>{1}-<i>&lt;active log file pattern&gt;</i></code></p>


      <a name="simplelog.rollover.period"/>
      <h3 class="propertyName">simplelog.rollover.period</h3>

      <p>
         Specifies how often the rollover strategy will be consulted to decide whether to roll or not.
         Must be a positive integer in seconds.
      </p>

      <p>Default: <code>60</code></p>


      <a name="simplelog.rollover.fileSize.size"/>
      <h3 class="propertyName">simplelog.rollover.fileSize.size</h3>

      <p>
         When '<code>fileSize</code>' rollover is in use, specifies the size at which log files should be rolled.
         Must be a positive integer followed by 'b' (bytes), 'K' (kilobytes), 'M' (megabytes), 'G'
         (gigabytes) or 'T' (terabytes).
      </p>

      <p>Default: <code>100M</code></p>


      <a name="simplelog.rollover.timeOfDay.time"/>
      <h3 class="propertyName">simplelog.rollover.timeOfDay.time</h3>

      <p>
         When '<code>timeOfDay</code>' rollover is in use, specifies the time of the day at which the logs should roll
         over. The value should be in hours and minutes, separated by a colon, e.g. 23:30 specifies half an
         hour past 11 PM.
      </p>

      <p>Default: <code>0:00</code> <i>(12 midnight)</i></p>


      <a name="simplelog.rollover.timeOfDay.timezone"/>
      <h3 class="propertyName">simplelog.rollover.timeOfDay.timezone</h3>

      <p>
         When '<code>timeOfDay</code>' rollover is in use, specifies the TimeZone in which the rollover time
         (simplelog.rollover.timeOfDay.time) is specified.
      </p>

      <p>
         The value should be any TimeZone ID accepted by
         <a href="http://java.sun.com/j2se/1.4/docs/api/java/util/TimeZone.html#getTimeZone(java.lang.String)">
            java.util.TimeZone.getTimeZone(String id)
         </a>
      </p>

      <p>
         This property can be used to set the rollover time based on a TimeZone other than that in which
         the process is running. This relinquishes the need to perform time difference calculations or to
         make changes as daylight savings times begin and end.
      </p>

      <p>
         Because on some systems it may be difficult to set the default TimeZone properly, it is
         recommended that you always set this property, even when the default TimeZone is desired.
      </p>

      <p>Default: <i>blank (Uses the system's default TimeZone)</i></p>

      <p class="copyright">
         Copyright (c) 2006 Graham Lea. All rights reserved.
      </p>

      <div class="bottomMenu">
         <h1>Simple Log User Guide</h1>
         <ul>
            <li><a href="quickStart.html">Quick&nbsp;Start</a></li>
            <li><a href="philosophy.html">Philosophy</a></li>
            <li><a href="recommendedUse.html">Recommended&nbsp;Use</a></li>
            <li><a href="properties.html">Properties</a></li>
            <li><a href="rollover.html">Log&nbsp;Rolling</a></li>
            <li><a href="log4jComparison.html">Comparison&nbsp;with&nbsp;Log4J</a></li>
            <li><a href="faq.html">FAQ</a></li>
            <li><a href="donations.html">Donations</a></li>
            <li><a href="meaningOfLife.html">The Meaning of Life</a></li>
            <li><a href="api/index.html">API Documentation</a></li>
         </ul>
      </div>

   </body>

</html>
